home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / nss / cmmf.h < prev    next >
C/C++ Source or Header  |  2006-04-20  |  45KB  |  1,123 lines
  1. /* -*- Mode: C; tab-width: 8 -*-*/
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is the Netscape security libraries.
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1994-2000
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37.  
  38. #ifndef _CMMF_H_
  39. #define _CMMF_H_
  40. /*
  41.  * These are the functions exported by the security library for 
  42.  * implementing Certificate Management Message Formats (CMMF).
  43.  *
  44.  * This API is designed against July 1998 CMMF draft.  Please read this
  45.  * draft before trying to use this API in an application that use CMMF.
  46.  */
  47. #include "seccomon.h"
  48. #include "cmmft.h"
  49. #include "crmf.h"
  50.  
  51. SEC_BEGIN_PROTOS
  52.  
  53. /******************* Creation Functions *************************/
  54.  
  55. /*
  56.  * FUNCTION: CMMF_CreateCertRepContent
  57.  * INPUTS:
  58.  *    NONE
  59.  * NOTES:
  60.  *    This function will create an empty CMMFCertRepContent Structure.  
  61.  *    The client of the library must set the CMMFCertResponses.
  62.  *    Call CMMF_CertRepContentSetCertResponse to accomplish this task.
  63.  *    If the client of the library also wants to include the chain of 
  64.  *    CA certs required to make the certificates in CMMFCertResponse valid, 
  65.  *    then the user must also set the caPubs field of CMMFCertRepContent.
  66.  *    Call CMMF_CertRepContentSetCAPubs to accomplish this.  After setting
  67.  *    the desired fields, the user can then call CMMF_EncodeCertRepContent 
  68.  *    to DER-encode the CertRepContent.
  69.  * RETURN:
  70.  *    A pointer to the CMMFCertRepContent.  A NULL return value indicates 
  71.  *    an error in allocating memory or failure to initialize the structure.
  72.  */
  73. extern CMMFCertRepContent* CMMF_CreateCertRepContent(void);
  74.  
  75. /*
  76.  * FUNCTION: CMMF_CreateCertRepContentFromDER
  77.  * INPUTS
  78.  *    db
  79.  *        The certificate database where the certificates will be placed.
  80.  *        The certificates will be placed in the temporary database associated
  81.  *        with the handle. 
  82.  *    buf
  83.  *        A buffer to the DER-encoded CMMFCertRepContent
  84.  *    len
  85.  *        The length in bytes of the buffer 'buf'
  86.  * NOTES:
  87.  *    This function passes the buffer to the ASN1 decoder and creates a
  88.  *    CMMFCertRepContent structure.  The user must call 
  89.  *    CMMF_DestroyCertRepContent after the return value is no longer needed.
  90.  *
  91.  * RETURN:
  92.  *    A pointer to the CMMFCertRepContent structure.  A NULL return
  93.  *    value indicates the library was unable to parse the DER.
  94.  */
  95. extern CMMFCertRepContent* 
  96.        CMMF_CreateCertRepContentFromDER(CERTCertDBHandle *db, 
  97.                     const char       *buf, 
  98.                     long              len);
  99.  
  100. /*
  101.  * FUNCTION: CMMF_CreateCertResponse
  102.  * INPUTS:
  103.  *    inCertReqId
  104.  *        The Certificate Request Id this response is for.
  105.  * NOTES:
  106.  *    This creates a CMMFCertResponse.  This response should correspond
  107.  *    to a request that was received via CRMF.  From the CRMF message you
  108.  *    can get the Request Id to pass in as inCertReqId, in essence binding 
  109.  *    a CMRFCertRequest message to the CMMFCertResponse created by this
  110.  *    function.  If no requuest id is associated with the response to create
  111.  *    then the user should pass in -1 for 'inCertReqId'.
  112.  *
  113.  * RETURN:
  114.  *    A pointer to the new CMMFCertResponse corresponding to the request id 
  115.  *    passed in.  A NULL return value indicates an error while trying to 
  116.  *    create the CMMFCertResponse.
  117.  */
  118. extern CMMFCertResponse* CMMF_CreateCertResponse(long inCertReqId);
  119.  
  120. /*
  121.  * FUNCTION: CMMF_CreateKeyRecRepContent
  122.  * INPUTS:
  123.  *    NONE
  124.  * NOTES:
  125.  *    This function creates a new empty CMMFKeyRecRepContent structure.
  126.  *    At the very minimum, the user  must call 
  127.  *    CMMF_KeyRecRepContentSetPKIStatusInfoStatus field to have an
  128.  *    encodable structure.  Depending on what the response is, the user may
  129.  *    have to set other fields as well to properly build up the structure so
  130.  *    that it can be encoded.  Refer to the CMMF draft for how to properly
  131.  *    set up a CMMFKeyRecRepContent. This is the structure that an RA returns
  132.  *    to an end entity when doing key recovery.
  133.  
  134.  *    The user must call CMMF_DestroyKeyRecRepContent when the return value
  135.  *    is no longer needed.
  136.  * RETURN:
  137.  *    A pointer to the empty CMMFKeyRecRepContent.  A return value of NULL
  138.  *    indicates an error in allocating memory or initializing the structure.
  139.  */
  140. extern CMMFKeyRecRepContent *CMMF_CreateKeyRecRepContent(void);
  141.  
  142. /*
  143.  * FUNCTION: CMMF_CreateKeyRecRepContentFromDER
  144.  * INPUTS:
  145.  *    db
  146.  *        The handle for the certificate database where the decoded 
  147.  *        certificates will be placed.  The decoded certificates will
  148.  *        be placed in the temporary database associated with the 
  149.  *        handle.
  150.  *    buf
  151.  *        A buffer contatining the DER-encoded CMMFKeyRecRepContent
  152.  *    len
  153.  *        The length in bytes of the buffer 'buf'
  154.  * NOTES
  155.  *    This function passes the buffer to the ASN1 decoder and creates a 
  156.  *    CMMFKeyRecRepContent structure.
  157.  *
  158.  * RETURN:
  159.  *    A pointer to the CMMFKeyRecRepContent structure.  A NULL return
  160.  *    value indicates the library was unable to parse the DER.
  161.  */
  162. extern CMMFKeyRecRepContent* 
  163.        CMMF_CreateKeyRecRepContentFromDER(CERTCertDBHandle *db,
  164.                       const char       *buf,
  165.                       long              len);
  166.  
  167. /*
  168.  * FUNCTION: CMMF_CreatePOPODecKeyChallContent
  169.  * INPUTS:
  170.  *    NONE
  171.  * NOTES:
  172.  *    This function creates an empty CMMFPOPODecKeyChallContent.  The user
  173.  *    must add the challenges individually specifying the random number to
  174.  *    be used and the public key to be used when creating each individual 
  175.  *    challenge.  User can accomplish this by calling the function 
  176.  *    CMMF_POPODecKeyChallContentSetNextChallenge.
  177.  * RETURN:
  178.  *    A pointer to a CMMFPOPODecKeyChallContent structure.  Ther user can
  179.  *    then call CMMF_EncodePOPODecKeyChallContent passing in the return
  180.  *    value from this function after setting all of the challenges.  A 
  181.  *    return value of NULL indicates an error while creating the 
  182.  *    CMMFPOPODecKeyChallContent structure.
  183.  */
  184. extern CMMFPOPODecKeyChallContent*
  185.        CMMF_CreatePOPODecKeyChallContent(void);
  186.  
  187. /*
  188.  * FUNCTION: CMMF_CreatePOPODecKeyChallContentFromDER
  189.  * INPUTS
  190.  *    buf
  191.  *        A buffer containing the DER-encoded CMMFPOPODecKeyChallContent
  192.  *    len
  193.  *        The length in bytes of the buffer 'buf'
  194.  * NOTES:
  195.  *    This function passes the buffer to the ASN1 decoder and creates a
  196.  *    CMMFPOPODecKeyChallContent structure.  
  197.  *
  198.  * RETURN:
  199.  *    A pointer to the CMMFPOPODecKeyChallContent structure.  A NULL return
  200.  *    value indicates the library was unable to parse the DER.
  201.  */
  202. extern CMMFPOPODecKeyChallContent*
  203.        CMMF_CreatePOPODecKeyChallContentFromDER(const char *buf, long len);
  204.  
  205. /*
  206.  * FUNCTION: CMMF_CreatePOPODecKeyRespContentFromDER
  207.  * INPUTS:
  208.  *    buf
  209.  *        A buffer contatining the DER-encoded CMMFPOPODecKeyRespContent
  210.  *    len
  211.  *        The length in bytes of the buffer 'buf'
  212.  * NOTES
  213.  *    This function passes the buffer to the ASN1 decoder and creates a 
  214.  *    CMMFPOPODecKeyRespContent structure.
  215.  *
  216.  * RETURN:
  217.  *    A pointer to the CMMFPOPODecKeyRespContent structure.  A NULL return
  218.  *    value indicates the library was unable to parse the DER.
  219.  */
  220. extern CMMFPOPODecKeyRespContent*
  221.        CMMF_CreatePOPODecKeyRespContentFromDER(const char *buf, long len);
  222.  
  223. /************************** Set Functions *************************/
  224.  
  225. /*
  226.  * FUNCTION: CMMF_CertRepContentSetCertResponses
  227.  * INPUTS:
  228.  *    inCertRepContent
  229.  *        The CMMFCertRepContent to operate on.
  230.  *    inCertResponses
  231.  *        An array of pointers to CMMFCertResponse structures to 
  232.  *        add to the CMMFCertRepContent structure.
  233.  *    inNumResponses
  234.  *        The length of the array 'inCertResponses'
  235.  * NOTES:
  236.  *    This function will add the CMMFCertResponse structure to the 
  237.  *    CMMFCertRepContent passed in.  The CMMFCertResponse field of 
  238.  *    CMMFCertRepContent is required, so the client must call this function
  239.  *    before calling CMMF_EncodeCertRepContent.  If the user calls 
  240.  *    CMMF_EncodeCertRepContent before calling this function, 
  241.  *    CMMF_EncodeCertRepContent will fail.
  242.  *
  243.  * RETURN:
  244.  *    SECSuccess if adding the CMMFCertResponses to the CMMFCertRepContent
  245.  *    structure was successful.  Any other return value indicates an error
  246.  *    while trying to add the CMMFCertResponses.
  247.  */
  248. extern SECStatus 
  249.       CMMF_CertRepContentSetCertResponses(CMMFCertRepContent *inCertRepContent,
  250.                       CMMFCertResponse  **inCertResponses,
  251.                       int                 inNumResponses);
  252.  
  253. /*
  254.  * FUNCTION: CMMF_CertRepContentSetCAPubs
  255.  * INPUTS:
  256.  *    inCertRepContent
  257.  *        The CMMFCertRepContent to operate on.
  258.  *    inCAPubs
  259.  *        The certificate list which makes up the chain of CA certificates
  260.  *        required to make the issued cert valid.
  261.  * NOTES:
  262.  *    This function will set the the certificates in the CA chain as part
  263.  *    of the CMMFCertRepContent.  This field is an optional member of the 
  264.  *    CMMFCertRepContent structure, so the client is not required to call
  265.  *    this function before calling CMMF_EncodeCertRepContent.
  266.  *
  267.  * RETURN:
  268.  *    SECSuccess if adding the 'inCAPubs' to the CERTRepContent was successful.
  269.  *    Any other return value indicates an error while adding 'inCAPubs' to the 
  270.  *    CMMFCertRepContent structure.
  271.  * 
  272.  */
  273. extern SECStatus 
  274.        CMMF_CertRepContentSetCAPubs (CMMFCertRepContent  *inCertRepContent,
  275.                      CERTCertList        *inCAPubs);
  276.  
  277. /*
  278.  * FUNCTION: CMMF_CertResponseSetPKIStatusInfoStatus
  279.  * INPUTS:
  280.  *    inCertResp
  281.  *        The CMMFCertResponse to operate on.
  282.  *     inPKIStatus
  283.  *        The value to set for the PKIStatusInfo.status field.
  284.  * NOTES:
  285.  *    This function will set the CertResponse.status.status field of 
  286.  *    the CMMFCertResponse structure.  (View the definition of CertResponse
  287.  *    in the CMMF draft to see exactly which value this talks about.)  This
  288.  *    field is a required member of the structure, so the user must call this
  289.  *    function in order to have a CMMFCertResponse that can be encoded.
  290.  *
  291.  * RETURN:
  292.  *    SECSuccess if setting the field with the passed in value was successful.
  293.  *    Any other return value indicates an error while trying to set the field.
  294.  */
  295. extern SECStatus 
  296.      CMMF_CertResponseSetPKIStatusInfoStatus (CMMFCertResponse *inCertResp,
  297.                           CMMFPKIStatus     inPKIStatus);
  298.  
  299. /*
  300.  * FUNCTION: CMMF_CertResponseSetCertificate
  301.  * INPUTS:
  302.  *    inCertResp
  303.  *        The CMMFCertResponse to operate on.
  304.  *    inCertificate
  305.  *        The certificate to add to the 
  306.  *        CertResponse.CertifiedKeyPair.certOrEncCert.certificate field.
  307.  * NOTES:
  308.  *    This function will take the certificate and make it a member of the
  309.  *    CMMFCertResponse.  The certificate should be the actual certificate
  310.  *    being issued via the response.
  311.  *
  312.  * RETURN:
  313.  *    SECSuccess if adding the certificate to the response was successful.
  314.  *    Any other return value indicates an error in adding the certificate to
  315.  *    the CertResponse.
  316.  */
  317. extern SECStatus 
  318.        CMMF_CertResponseSetCertificate (CMMFCertResponse *inCertResp,
  319.                     CERTCertificate  *inCertificate);
  320.  
  321. /*
  322.  * FUNCTION: CMMF_KeyRecRepContentSetPKIStatusInfoStatus
  323.  * INPUTS: 
  324.  *    inKeyRecRep
  325.  *        The CMMFKeyRecRepContent to operate on.
  326.  *    inPKIStatus
  327.  *        The value to set the PKIStatusInfo.status field to.
  328.  * NOTES:
  329.  *    This function sets the only required field for the KeyRecRepContent.
  330.  *    In most cases, the user will set this field and other fields of the
  331.  *    structure to properly create the CMMFKeyRecRepContent structure.  
  332.  *    Refer to the CMMF draft to see which fields need to be set in order
  333.  *    to create the desired CMMFKeyRecRepContent.
  334.  * 
  335.  * RETURN:
  336.  *    SECSuccess if setting the PKIStatusInfo.status field was successful.
  337.  *    Any other return value indicates an error in setting the field.
  338.  */
  339. extern SECStatus 
  340. CMMF_KeyRecRepContentSetPKIStatusInfoStatus(CMMFKeyRecRepContent *inKeyRecRep,
  341.                         CMMFPKIStatus         inPKIStatus);
  342.  
  343. /*
  344.  * FUNCTION: CMMF_KeyRecRepContentSetNewSignCert
  345.  * INPUTS:
  346.  *    inKeyRecRep
  347.  *        The CMMFKeyRecRepContent to operate on.
  348.  *    inNewSignCert
  349.  *        The new signing cert to add to the CMMFKeyRecRepContent structure.
  350.  * NOTES:
  351.  *    This function sets the new signeing cert in the CMMFKeyRecRepContent
  352.  *    structure.
  353.  *
  354.  * RETURN:
  355.  *    SECSuccess if setting the new signing cert was successful.  Any other 
  356.  *    return value indicates an error occurred while trying to add the
  357.  *    new signing certificate.
  358.  */
  359. extern SECStatus 
  360.        CMMF_KeyRecRepContentSetNewSignCert(CMMFKeyRecRepContent *inKeyRecRep,
  361.                        CERTCertificate     *inNewSignCert);
  362.  
  363. /*
  364.  * FUNCTION: CMMF_KeyRecRepContentSetCACerts
  365.  * INPUTS:
  366.  *    inKeyRecRep
  367.  *        The CMMFKeyRecRepContent to operate on.
  368.  *    inCACerts
  369.  *        The list of CA certificates required to construct a valid 
  370.  *        certificate chain with the certificates that will be returned
  371.  *        to the end user via this KeyRecRepContent.
  372.  * NOTES:
  373.  *    This function sets the caCerts that are required to form a chain with the
  374.  *    end entity certificates that are being re-issued in this 
  375.  *    CMMFKeyRecRepContent structure.
  376.  *
  377.  * RETURN:
  378.  *    SECSuccess if adding the caCerts was successful.  Any other return value
  379.  *    indicates an error while tring to add the caCerts.
  380.  */
  381. extern SECStatus 
  382.        CMMF_KeyRecRepContentSetCACerts(CMMFKeyRecRepContent *inKeyRecRep,
  383.                        CERTCertList         *inCACerts);
  384.  
  385. /*
  386.  * FUNCTION: CMMF_KeyRecRepContentSetCertifiedKeyPair
  387.  * INPUTS:
  388.  *    inKeyRecRep
  389.  *        The CMMFKeyRecRepContent to operate on.
  390.  *    inCert
  391.  *        The certificate to add to the CMMFKeyRecRepContent structure.
  392.  *    inPrivKey
  393.  *        The private key associated with the certificate above passed in.
  394.  *    inPubKey
  395.  *        The public key to use for wrapping the private key.
  396.  * NOTES:
  397.  *    This function adds another certificate-key pair to the 
  398.  *    CMMFKeyRecRepcontent structure.  There may be more than one 
  399.  *    certificate-key pair in the structure, so the user must call this 
  400.  *    function multiple times to add more than one cert-key pair.
  401.  *
  402.  * RETURN:
  403.  *    SECSuccess if adding the certified key pair was successful.  Any other
  404.  *    return value indicates an error in adding certified key pair to 
  405.  *    CMMFKeyRecRepContent structure.
  406.  */
  407. extern SECStatus 
  408.     CMMF_KeyRecRepContentSetCertifiedKeyPair(CMMFKeyRecRepContent *inKeyRecRep,
  409.                          CERTCertificate      *inCert,
  410.                          SECKEYPrivateKey     *inPrivKey,
  411.                          SECKEYPublicKey      *inPubKey);
  412.  
  413. /*
  414.  * FUNCTION: CMMF_POPODecKeyChallContentSetNextChallenge
  415.  * INPUTS:
  416.  *    inDecKeyChall
  417.  *        The CMMFPOPODecKeyChallContent to operate on.
  418.  *    inRandom
  419.  *        The random number to use when generating the challenge,
  420.  *    inSender
  421.  *        The GeneralName representation of the sender of the challenge.
  422.  *    inPubKey
  423.  *        The public key to use when encrypting the challenge.
  424.  *    passwdArg
  425.  *        This value will be passed to the function used for getting a
  426.  *        password.  The password for getting a password should be registered
  427.  *        by calling PK11_SetPasswordFunc before this function is called. 
  428.  *        If no password callback is registered and the library needs to 
  429.  *        authenticate to the slot for any reason, this function will fail.
  430.  * NOTES:
  431.  *    This function adds a challenge to the end of the list of challenges
  432.  *    contained by 'inDecKeyChall'.  Refer to the CMMF draft on how the
  433.  *    the random number passed in and the sender's GeneralName are used
  434.  *    to generate the challenge and witness fields of the challenge.  This
  435.  *    library will use SHA1 as the one-way function for generating the 
  436.  *    witess field of the challenge.
  437.  *
  438.  * RETURN:
  439.  *    SECSuccess if generating the challenge and adding to the end of list
  440.  *    of challenges was successful.  Any other return value indicates an error
  441.  *    while trying to generate the challenge.
  442.  */
  443. extern SECStatus
  444. CMMF_POPODecKeyChallContentSetNextChallenge
  445.                                    (CMMFPOPODecKeyChallContent *inDecKeyChall,
  446.                     long                        inRandom,
  447.                     CERTGeneralName            *inSender,
  448.                     SECKEYPublicKey            *inPubKey,
  449.                     void                       *passwdArg);
  450.  
  451.  
  452. /************************** Encoding Functions *************************/
  453.  
  454. /*
  455.  * FUNCTION: CMMF_EncodeCertRepContent
  456.  * INPUTS:
  457.  *    inCertRepContent
  458.  *        The CMMFCertRepContent to DER-encode.
  459.  *    inCallback
  460.  *        A callback function that the ASN1 encoder will call whenever it 
  461.  *        wants to write out DER-encoded bytes.  Look at the defintion of 
  462.  *        CRMFEncoderOutputCallback in crmft.h for a description of the
  463.  *        parameters to the function.
  464.  *    inArg
  465.  *        An opaque pointer to a user-supplied argument that will be passed
  466.  *        to the callback funtion whenever the function is called.
  467.  * NOTES:
  468.  *    The CMMF library will use the same DER-encoding scheme as the CRMF 
  469.  *    library.  In other words, when reading CRMF comments that pertain to
  470.  *    encoding, those comments apply to the CMMF libray as well.  
  471.  *    The callback function will be called multiple times, each time supplying
  472.  *    the next chunk of DER-encoded bytes.  The user must concatenate the 
  473.  *    output of each successive call to the callback in order to get the
  474.  *    entire DER-encoded CMMFCertRepContent structure.
  475.  *
  476.  * RETURN:
  477.  *    SECSuccess if encoding the CMMFCertRepContent was successful.  Any 
  478.  *    other return value indicates an error while decoding the structure.
  479.  */
  480. extern SECStatus 
  481.        CMMF_EncodeCertRepContent (CMMFCertRepContent        *inCertRepContent,
  482.                   CRMFEncoderOutputCallback  inCallback,
  483.                   void                      *inArg);
  484.  
  485. /*
  486.  * FUNCTION: CMMF_EncodeKeyRecRepContent
  487.  * INPUTS:
  488.  *    inKeyRecRep
  489.  *        The CMMFKeyRepContent to DER-encode.
  490.  *    inCallback
  491.  *        A callback function that the ASN1 encoder will call whenever it 
  492.  *        wants to write out DER-encoded bytes.  Look at the defintion of 
  493.  *        CRMFEncoderOutputCallback in crmft.h for a description of the
  494.  *        parameters to the function.
  495.  *    inArg
  496.  *        An opaque pointer to a user-supplied argument that will be passed
  497.  *        to the callback funtion whenever the function is called.
  498.  * NOTES:
  499.  *    The CMMF library will use the same DER-encoding scheme as the CRMF 
  500.  *    library.  In other words, when reading CRMF comments that pertain to
  501.  *    encoding, those comments apply to the CMMF libray as well.  
  502.  *    The callback function will be called multiple times, each time supplying
  503.  *    the next chunk of DER-encoded bytes.  The user must concatenate the 
  504.  *    output of each successive call to the callback in order to get the
  505.  *    entire DER-encoded CMMFCertRepContent structure.
  506.  *
  507.  * RETURN:
  508.  *    SECSuccess if encoding the CMMFKeyRecRepContent was successful.  Any 
  509.  *    other return value indicates an error while decoding the structure.
  510.  */
  511. extern SECStatus
  512.        CMMF_EncodeKeyRecRepContent(CMMFKeyRecRepContent      *inKeyRecRep,
  513.                    CRMFEncoderOutputCallback  inCallback,
  514.                    void                      *inArg);
  515.  
  516. /*
  517.  * FUNCTION: CMMF_EncodePOPODecKeyChallContent
  518.  * INPUTS:
  519.  *    inDecKeyChall
  520.  *        The CMMFDecKeyChallContent to operate on.
  521.  *    inCallback
  522.  *        A callback function that the ASN1 encoder will call whenever it 
  523.  *        wants to write out DER-encoded bytes.  Look at the defintion of 
  524.  *        CRMFEncoderOutputCallback in crmft.h for a description of the
  525.  *        parameters to the function.
  526.  *    inArg
  527.  *        An opaque pointer to a user-supplied argument that will be passed
  528.  *        to the callback function whenever the function is called.
  529.  * NOTES:
  530.  *    The CMMF library will use the same DER-encoding scheme as the CRMF 
  531.  *    library.  In other words, when reading CRMF comments that pertain to
  532.  *    encoding, those comments apply to the CMMF libray as well.  
  533.  *    The callback function will be called multiple times, each time supplying
  534.  *    the next chunk of DER-encoded bytes.  The user must concatenate the 
  535.  *    output of each successive call to the callback in order to get the
  536.  *    entire DER-encoded CMMFCertRepContent structure.
  537.  *    The DER will be an encoding of the type POPODecKeyChallContents, which
  538.  *    is just a sequence of challenges.
  539.  *
  540.  * RETURN:
  541.  *    SECSuccess if encoding was successful.  Any other return value indicates
  542.  *    an error in trying to encode the Challenges.
  543.  */
  544. extern SECStatus 
  545. CMMF_EncodePOPODecKeyChallContent(CMMFPOPODecKeyChallContent *inDecKeyChall,
  546.                   CRMFEncoderOutputCallback inCallback,
  547.                   void                     *inArg);
  548.  
  549. /*
  550.  * FUNCTION: CMMF_EncodePOPODecKeyRespContent
  551.  * INPUTS:
  552.  *    inDecodedRand
  553.  *        An array of integers to encode as the responses to 
  554.  *        CMMFPOPODecKeyChallContent.  The integers must be in the same order
  555.  *        as the challenges extracted from CMMFPOPODecKeyChallContent.
  556.  *    inNumRand
  557.  *        The number of random integers contained in the array 'inDecodedRand'
  558.  *    inCallback
  559.  *        A callback function that the ASN1 encoder will call whenever it 
  560.  *        wants to write out DER-encoded bytes.  Look at the defintion of 
  561.  *        CRMFEncoderOutputCallback in crmft.h for a description of the
  562.  *        parameters to the function.
  563.  *    inArg
  564.  *        An opaque pointer to a user-supplied argument that will be passed
  565.  *        to the callback funtion whenever the function is called.
  566.  * NOTES:
  567.  *    The CMMF library will use the same DER-encoding scheme as the CRMF 
  568.  *    library.  In other words, when reading CRMF comments that pertain to
  569.  *    encoding, those comments apply to the CMMF libray as well.  
  570.  *    The callback function will be called multiple times, each time supplying
  571.  *    the next chunk of DER-encoded bytes.  The user must concatenate the 
  572.  *    output of each successive call to the callback in order to get the
  573.  *    entire DER-encoded  POPODecKeyRespContent.
  574.  *
  575.  * RETURN:
  576.  *    SECSuccess if encoding was successful.  Any other return value indicates
  577.  *    an error in trying to encode the Challenges.
  578.  */
  579. extern SECStatus 
  580.       CMMF_EncodePOPODecKeyRespContent(long                     *inDecodedRand,
  581.                        int                       inNumRand,
  582.                        CRMFEncoderOutputCallback inCallback,
  583.                        void                     *inArg); 
  584.  
  585. /***************  Accessor function  ***********************************/
  586.  
  587. /*
  588.  * FUNCTION: CMMF_CertRepContentGetCAPubs
  589.  * INPUTS:
  590.  *    inCertRepContent
  591.  *        The CMMFCertRepContent to extract the caPubs from.
  592.  * NOTES:
  593.  *    This function will return a copy of the list of certificates that
  594.  *    make up the chain of CA's required to make the cert issued valid.
  595.  *    The user must call CERT_DestroyCertList on the return value when 
  596.  *    done using the return value.  
  597.  *
  598.  *    Only call this function on a CertRepContent that has been decoded.
  599.  *    The client must call CERT_DestroyCertList when the certificate list
  600.  *    is no longer needed. 
  601.  *
  602.  *    The certs in the list will not be in the temporary database.  In order
  603.  *    to make these certificates a part of the permanent CA internal database,
  604.  *    the user must collect the der for all of these certs and call 
  605.  *    CERT_ImportCAChain.  Afterwards the certs will be part of the permanent
  606.  *    database.
  607.  *    
  608.  * RETURN:
  609.  *    A pointer to the CERTCertList representing the CA chain associated 
  610.  *    with the issued cert.  A NULL return value indicates  that no CA Pubs
  611.  *    were available in the CMMFCertRepContent structure. 
  612.  */
  613. extern CERTCertList* 
  614.        CMMF_CertRepContentGetCAPubs (CMMFCertRepContent *inCertRepContent);
  615.  
  616.  
  617. /*
  618.  * FUNCTION: CMMF_CertRepContentGetNumResponses
  619.  * INPUTS:
  620.  *    inCertRepContent
  621.  *        The CMMFCertRepContent to operate on.
  622.  * NOTES:
  623.  *    This function will return the number of CertResponses that are contained
  624.  *    by the CMMFCertRepContent passed in.
  625.  * 
  626.  * RETURN:
  627.  *    The number of CMMFCertResponses contained in the structure passed in.
  628.  */
  629. extern int 
  630.  CMMF_CertRepContentGetNumResponses (CMMFCertRepContent *inCertRepContent);
  631.  
  632. /*
  633.  * FUNCTION: CMMF_CertRepContentGetResponseAtIndex
  634.  * INPUTS:
  635.  *    inCertRepContent
  636.  *        The CMMFCertRepContent to operate on.
  637.  *    inIndex
  638.  *        The index of the CMMFCertResponse the user wants a copy of.
  639.  * NOTES:
  640.  *    This funciton creates a copy of the CMMFCertResponse at the index 
  641.  *    corresponding to the parameter 'inIndex'.  Indexing is done like a
  642.  *    traditional C array, ie the valid indexes are (0...numResponses-1).
  643.  *    The user must call CMMF_DestroyCertResponse after the return value is 
  644.  *    no longer needed.
  645.  *
  646.  * RETURN:
  647.  *    A pointer to the CMMFCertResponse at the index corresponding to 
  648.  *    'inIndex'.  A return value of NULL indicates an error in copying 
  649.  *    the CMMFCertResponse.
  650.  */
  651. extern CMMFCertResponse*
  652. CMMF_CertRepContentGetResponseAtIndex (CMMFCertRepContent *inCertRepContent,
  653.                        int                 inIndex);
  654.  
  655. /*
  656.  * FUNCTION: CMMF_CertResponseGetCertReqId
  657.  * INPUTS:
  658.  *    inCertResp
  659.  *        The CMMFCertResponse to operate on.
  660.  * NOTES:
  661.  *    This function returns the CertResponse.certReqId from the 
  662.  *    CMMFCertResponse structure passed in.  If the return value is -1, that
  663.  *    means there is no associated certificate request with the CertResponse.
  664.  * RETURN:
  665.  *    A long representing the id of the certificate request this 
  666.  *    CMMFCertResponse corresponds to.  A return value of -1 indicates an
  667.  *    error in extracting the value of the integer.
  668.  */
  669. extern long CMMF_CertResponseGetCertReqId(CMMFCertResponse *inCertResp);
  670.  
  671. /*
  672.  * FUNCTION: CMMF_CertResponseGetPKIStatusInfoStatus
  673.  * INPUTS:
  674.  *    inCertResp
  675.  *        The CMMFCertResponse to operate on.
  676.  * NOTES:
  677.  *    This function returns the CertResponse.status.status field of the 
  678.  *    CMMFCertResponse structure.
  679.  *
  680.  * RETURN:
  681.  *    The enumerated value corresponding to the PKIStatus defined in the CMMF
  682.  *    draft.  See the CMMF draft for the definition of PKIStatus.  See crmft.h
  683.  *    for the definition of CMMFPKIStatus.
  684.  */
  685. extern CMMFPKIStatus 
  686.        CMMF_CertResponseGetPKIStatusInfoStatus(CMMFCertResponse *inCertResp);
  687.  
  688. /*
  689.  * FUNCTION: CMMF_CertResponseGetCertificate
  690.  * INPUTS:
  691.  *    inCertResp
  692.  *        The Certificate Response to operate on.
  693.  *    inCertdb
  694.  *        This is the certificate database where the function will place the
  695.  *        newly issued certificate.
  696.  * NOTES:
  697.  *    This function retrieves the CertResponse.certifiedKeyPair.certificate
  698.  *    from the CMMFCertResponse.  The user will get a copy of that certificate
  699.  *    so  the user must call CERT_DestroyCertificate when the return value is 
  700.  *    no longer needed.  The certificate returned will be in the temporary 
  701.  *    certificate database.
  702.  *
  703.  * RETURN:
  704.  *    A pointer to a copy of the certificate contained within the 
  705.  *    CMMFCertResponse.  A return value of NULL indicates an error while trying
  706.  *    to make a copy of the certificate.
  707.  */
  708. extern CERTCertificate*
  709.        CMMF_CertResponseGetCertificate(CMMFCertResponse *inCertResp,
  710.                                        CERTCertDBHandle *inCertdb);
  711.  
  712. /*
  713.  * FUNCTION: CMMF_KeyRecRepContentGetPKIStatusInfoStatus
  714.  * INPUTS:
  715.  *    inKeyRecRep
  716.  *        The CMMFKeyRecRepContent structure to operate on.
  717.  * NOTES:
  718.  *    This function retrieves the KeyRecRepContent.status.status field of 
  719.  *    the CMMFKeyRecRepContent structure.
  720.  * RETURN:
  721.  *    The CMMFPKIStatus corresponding to the value held in the 
  722.  *    CMMFKeyRecRepContent structure.
  723.  */
  724. extern CMMFPKIStatus 
  725. CMMF_KeyRecRepContentGetPKIStatusInfoStatus(CMMFKeyRecRepContent *inKeyRecRep);
  726.  
  727. /*
  728.  * FUNCTION: CMMF_KeyRecRepContentGetNewSignCert
  729.  * INPUTS:
  730.  *    inKeyRecRep
  731.  *        The CMMFKeyRecRepContent to operate on.
  732.  * NOTES:
  733.  *    This function retrieves the KeyRecRepContent.newSignCert field of the
  734.  *    CMMFKeyRecRepContent structure.  The user must call 
  735.  *    CERT_DestroyCertificate when the return value is no longer needed. The
  736.  *    returned certificate will be in the temporary database.  The user 
  737.  *    must then place the certificate permanently in whatever token the
  738.  *    user determines is the proper destination.  A return value of NULL
  739.  *    indicates the newSigCert field was not present.
  740.  */
  741. extern CERTCertificate*
  742.        CMMF_KeyRecRepContentGetNewSignCert(CMMFKeyRecRepContent *inKeyRecRep);
  743.  
  744. /*
  745.  * FUNCTION: CMMF_KeyRecRepContentGetCACerts
  746.  * INPUTS:
  747.  *    inKeyRecRep
  748.  *        The CMMFKeyRecRepContent to operate on.
  749.  * NOTES:
  750.  *    This function returns a CERTCertList which contains all of the 
  751.  *    certficates that are in the sequence KeyRecRepContent.caCerts
  752.  *    User must call CERT_DestroyCertList when the return value is no longer 
  753.  *    needed.  All of these certificates will be placed in the tempoaray
  754.  *    database.
  755.  *
  756.  * RETURN:
  757.  *    A pointer to the list of caCerts contained in the CMMFKeyRecRepContent
  758.  *    structure.  A return value of NULL indicates the library was not able to 
  759.  *    make a copy of the certifcates.  This may be because there are no caCerts
  760.  *    included in the CMMFKeyRecRepContent strucure or an internal error.  Call
  761.  *    CMMF_KeyRecRepContentHasCACerts to find out if there are any caCerts 
  762.  *    included in 'inKeyRecRep'.
  763.  */
  764. extern CERTCertList*
  765.        CMMF_KeyRecRepContentGetCACerts(CMMFKeyRecRepContent *inKeyRecRep);
  766.  
  767. /*
  768.  * FUNCTION: CMMF_KeyRecRepContentGetNumKeyPairs
  769.  * INPUTS:
  770.  *    inKeyRecRep
  771.  *        The CMMFKeyRecRepContent to operate on.
  772.  * RETURN:
  773.  *    This function returns the number of CMMFCertifiedKeyPair structures that
  774.  *    that are stored in the KeyRecRepContent structure.
  775.  */
  776. extern int 
  777.        CMMF_KeyRecRepContentGetNumKeyPairs(CMMFKeyRecRepContent *inKeyRecRep);
  778.  
  779. /*
  780.  * FUNCTION: CMMF_KeyRecRepContentGetCertKeyAtIndex
  781.  * INPUTS:
  782.  *    inKeyRecRepContent
  783.  *        The CMMFKeyRecRepContent to operate on.
  784.  *    inIndex
  785.  *        The index of the desired CMMFCertifiedKeyPair
  786.  * NOTES:
  787.  *    This function retrieves the CMMFCertifiedKeyPair structure at the index
  788.  *    'inIndex'.  Valid indexes are 0...(numKeyPairs-1)  The user must call 
  789.  *    CMMF_DestroyCertifiedKeyPair when the return value is no longer needed.
  790.  *
  791.  * RETURN:
  792.  *    A pointer to the Certified Key Pair at the desired index.  A return value
  793.  *    of NULL indicates an error in extracting the Certified Key Pair at the 
  794.  *    desired index.
  795.  */
  796. extern CMMFCertifiedKeyPair*
  797.       CMMF_KeyRecRepContentGetCertKeyAtIndex(CMMFKeyRecRepContent *inKeyRecRep,
  798.                          int                   inIndex);
  799.  
  800. /*
  801.  * FUNCTION: CMMF_CertifiedKeyPairGetCertificate
  802.  * INPUTS:
  803.  *    inCertKeyPair
  804.  *        The CMMFCertifiedKeyPair to operate on.
  805.  *    inCertdb
  806.  *        The database handle for the database you want this certificate
  807.  *        to wind up in.
  808.  * NOTES:
  809.  *    This function retrieves the certificate at 
  810.  *    CertifiedKeyPair.certOrEncCert.certificate
  811.  *    The user must call CERT_DestroyCertificate when the return value is no
  812.  *    longer needed.  The user must import this certificate as a token object
  813.  *    onto PKCS#11 slot in order to make it a permanent object.  The returned
  814.  *    certificate will be in the temporary database.
  815.  * 
  816.  * RETURN:
  817.  *    A pointer to the certificate contained within the certified key pair.
  818.  *    A return value of NULL indicates an error in creating the copy of the 
  819.  *    certificate.
  820.  */
  821. extern CERTCertificate*
  822.       CMMF_CertifiedKeyPairGetCertificate(CMMFCertifiedKeyPair *inCertKeyPair,
  823.                       CERTCertDBHandle     *inCertdb);
  824.  
  825. /*
  826.  * FUNCTION: CMMF_POPODecKeyChallContentGetNumChallenges
  827.  * INPUTS:
  828.  *    inKeyChallCont
  829.  *        The CMMFPOPODecKeyChallContent to operate on.
  830.  * RETURN:
  831.  *    This function returns the number of CMMFChallenges are contained in 
  832.  *    the CMMFPOPODecKeyChallContent structure.
  833.  */
  834. extern int CMMF_POPODecKeyChallContentGetNumChallenges
  835.                                   (CMMFPOPODecKeyChallContent *inKeyChallCont);
  836.  
  837. /*
  838.  * FUNCTION: CMMF_POPODecKeyChallContentGetPublicValue
  839.  * ---------------------------------------------------
  840.  * INPUTS:
  841.  *    inKeyChallCont
  842.  *        The CMMFPOPODecKeyChallContent to operate on.
  843.  *    inIndex
  844.  *        The index of the Challenge within inKeyChallCont to operate on.
  845.  *        Indexes start from 0, ie the Nth Challenge corresponds to index
  846.  *        N-1.
  847.  * NOTES:
  848.  * This function retrieves the public value stored away in the Challenge at
  849.  * index inIndex of inKeyChallCont.
  850.  * RETURN:
  851.  * A pointer to a SECItem containing the public value.  User must call 
  852.  * SECITEM_FreeItem on the return value when the value is no longer necessary.
  853.  * A return value of NULL indicates an error while retrieving the public value.
  854.  */
  855. extern SECItem* CMMF_POPODecKeyChallContentGetPublicValue
  856.                                    (CMMFPOPODecKeyChallContent *inKeyChallCont,
  857.                     int                         inIndex);
  858.  
  859.  
  860. /*
  861.  * FUNCTION: CMMF_POPODecKeyChallContentGetRandomNumber
  862.  * INPUTS:
  863.  *    inChallContent
  864.  *        The CMMFPOPODecKeyChallContent to operate on.
  865.  *    inIndex
  866.  *        The index of the challenge to look at.  Valid indexes are 0 through
  867.  *        (CMMF_POPODecKeyChallContentGetNumChallenges(inChallContent) - 1).
  868.  *    inDest
  869.  *        A pointer to a user supplied buffer where the library
  870.  *        can place a copy of the random integer contatained in the
  871.  *        challenge.
  872.  * NOTES:
  873.  *    This function returns the value held in the decrypted Rand structure
  874.  *    corresponding to the random integer.  The user must call 
  875.  *    CMMF_POPODecKeyChallContentDecryptChallenge before calling this function.  Call 
  876.  *    CMMF_ChallengeIsDecrypted to find out if the challenge has been 
  877.  *    decrypted.
  878.  *
  879.  * RETURN:
  880.  *    SECSuccess indicates the witness field has been previously decrypted
  881.  *    and the value for the random integer was successfully placed at *inDest.
  882.  *    Any other return value indicates an error and that the value at *inDest
  883.  *    is not a valid value.
  884.  */
  885. extern SECStatus CMMF_POPODecKeyChallContentGetRandomNumber
  886.                                       (CMMFPOPODecKeyChallContent *inKeyChallCont,
  887.                        int                          inIndex,
  888.                        long                        *inDest);
  889.  
  890. /*
  891.  * FUNCTION: CMMF_POPODecKeyRespContentGetNumResponses
  892.  * INPUTS:
  893.  *    inRespCont
  894.  *        The POPODecKeyRespContent to operate on.
  895.  * RETURN:
  896.  * This function returns the number of responses contained in inRespContent.
  897.  */
  898. extern int 
  899.  CMMF_POPODecKeyRespContentGetNumResponses(CMMFPOPODecKeyRespContent *inRespCont);
  900.  
  901. /*
  902.  * FUNCTION: CMMF_POPODecKeyRespContentGetResponse
  903.  * INPUTS:
  904.  *    inRespCont
  905.  *        The POPODecKeyRespContent to operate on.
  906.  *    inIndex
  907.  *        The index of the response to retrieve.
  908.  *        The Nth response is at index N-1, ie the 1st response is at index 0,
  909.  *        the 2nd response is at index 1, and so on.
  910.  *    inDest
  911.  *        A pointer to a pre-allocated buffer where the library can put the 
  912.  *        value of the response located at inIndex.
  913.  * NOTES:
  914.  * The function returns the response contained at index inIndex.  
  915.  * CMMFPOPODecKeyRespContent is a structure that the server will generally 
  916.  * get in response to a CMMFPOPODecKeyChallContent.  The server will expect
  917.  * to see the responses in the same order as it constructed them in 
  918.  * the CMMFPOPODecKeyChallContent structure.
  919.  * RETURN:
  920.  * SECSuccess if getting the response at the desired index was successful.  Any
  921.  * other return value indicates an errror.
  922.  */
  923. extern SECStatus
  924.      CMMF_POPODecKeyRespContentGetResponse (CMMFPOPODecKeyRespContent *inRespCont,
  925.                         int                        inIndex,
  926.                         long                      *inDest);
  927.  
  928. /************************* Destructor Functions ******************************/
  929.  
  930. /*
  931.  * FUNCTION: CMMF_DestroyCertResponse
  932.  * INPUTS:
  933.  *    inCertResp
  934.  *        The CMMFCertResponse to destroy.
  935.  * NOTES:
  936.  *    This function frees all the memory associated with the CMMFCertResponse
  937.  *    passed in.
  938.  * RETURN:
  939.  *    SECSuccess if freeing the memory was successful.  Any other return value
  940.  *    indicates an error while freeing the memory.
  941.  */
  942. extern SECStatus CMMF_DestroyCertResponse(CMMFCertResponse *inCertResp);
  943.  
  944. /*
  945.  * FUNCTION: CMMF_DestroyCertRepContent
  946.  * INPUTS:
  947.  *    inCertRepContent
  948.  *        The CMMFCertRepContent to destroy
  949.  * NOTES:
  950.  *    This function frees the memory associated with the CMMFCertRepContent
  951.  *    passed in.
  952.  * RETURN:
  953.  *    SECSuccess if freeing all the memory associated with the 
  954.  *    CMMFCertRepContent passed in is successful.  Any other return value 
  955.  *    indicates an error while freeing the memory.
  956.  */
  957. extern SECStatus 
  958.        CMMF_DestroyCertRepContent (CMMFCertRepContent *inCertRepContent);
  959.  
  960. /*
  961.  * FUNCTION: CMMF_DestroyKeyRecRepContent
  962.  * INPUTS:
  963.  *    inKeyRecRep
  964.  *        The CMMFKeyRecRepContent to destroy.
  965.  * NOTES:
  966.  *    This function destroys all the memory associated with the 
  967.  *    CMMFKeyRecRepContent passed in.
  968.  *
  969.  * RETURN:
  970.  *    SECSuccess if freeing all the memory is successful.  Any other return 
  971.  *    value indicates an error in freeing the memory.
  972.  */
  973. extern SECStatus 
  974.        CMMF_DestroyKeyRecRepContent(CMMFKeyRecRepContent *inKeyRecRep);
  975.  
  976. /*
  977.  * FUNCTION: CMMF_DestroyCertifiedKeyPair
  978.  * INPUTS:
  979.  *    inCertKeyPair
  980.  *        The CMMFCertifiedKeyPair to operate on.
  981.  * NOTES: 
  982.  *    This function frees up all the memory associated with 'inCertKeyPair'
  983.  *
  984.  * RETURN:
  985.  *    SECSuccess if freeing all the memory associated with 'inCertKeyPair'
  986.  *    is successful.  Any other return value indicates an error while trying
  987.  *    to free the memory.
  988.  */
  989. extern SECStatus 
  990.        CMMF_DestroyCertifiedKeyPair(CMMFCertifiedKeyPair *inCertKeyPair);
  991.  
  992. /*
  993.  * FUNCTION: CMMF_DestroyPOPODecKeyRespContent
  994.  * INPUTS:
  995.  *    inDecKeyResp
  996.  *        The CMMFPOPODecKeyRespContent structure to free.
  997.  * NOTES:
  998.  *    This function frees up all the memory associate with the 
  999.  *    CMMFPOPODecKeyRespContent.
  1000.  *
  1001.  * RETURN:
  1002.  *    SECSuccess if freeing up all the memory associated with the
  1003.  *    CMMFPOPODecKeyRespContent structure is successful.  Any other
  1004.  *    return value indicates an error while freeing the memory.
  1005.  */
  1006. extern SECStatus
  1007.        CMMF_DestroyPOPODecKeyRespContent(CMMFPOPODecKeyRespContent *inDecKeyResp);
  1008.  
  1009.  
  1010. /************************** Miscellaneous Functions *************************/
  1011.  
  1012. /*
  1013.  * FUNCTION: CMMF_CertifiedKeyPairUnwrapPrivKey
  1014.  * INPUTS:
  1015.  *    inCertKeyPair
  1016.  *        The CMMFCertifiedKeyPair to operate on.
  1017.  *    inPrivKey
  1018.  *        The private key to use to un-wrap the private key
  1019.  *    inNickName
  1020.  *        This is the nickname that will be associated with the private key
  1021.  *        to be unwrapped.
  1022.  *    inSlot
  1023.  *        The PKCS11 slot where the unwrapped private key should end up.
  1024.  *    inCertdb
  1025.  *        The Certificate database with which the new key will be associated.
  1026.  *    destPrivKey
  1027.  *        A pointer to memory where the library can place a pointer to the
  1028.  *        private key after importing the key onto the specified slot.
  1029.  *    wincx
  1030.  *        An opaque pointer that the library will use in a callback function
  1031.  *        to get the password if necessary.
  1032.  *    
  1033.  * NOTES:
  1034.  *    This function uses the private key passed in to unwrap the private key
  1035.  *    contained within the CMMFCertifiedKeyPair structure. After this 
  1036.  *    function successfully returns, the private key has been unwrapped and
  1037.  *    placed in the specified slot. 
  1038.  *
  1039.  * RETURN:
  1040.  *    SECSuccess if unwrapping the private key was successful.  Any other 
  1041.  *    return value indicates an error while trying to un-wrap the private key.
  1042.  */
  1043. extern SECStatus 
  1044.        CMMF_CertifiedKeyPairUnwrapPrivKey(CMMFCertifiedKeyPair *inKeyPair,
  1045.                       SECKEYPrivateKey     *inPrivKey,
  1046.                       SECItem              *inNickName,
  1047.                       PK11SlotInfo         *inSlot,
  1048.                                           CERTCertDBHandle     *inCertdb,
  1049.                       SECKEYPrivateKey    **destPrivKey,
  1050.                       void                 *wincx);
  1051.  
  1052. /*
  1053.  * FUNCTION: CMMF_KeyRecRepContentHasCACerts
  1054.  * INPUTS:
  1055.  *    inKeyRecRecp
  1056.  *        The CMMFKeyRecRepContent to operate on.
  1057.  * RETURN:
  1058.  *    This function returns PR_TRUE if there are one or more certificates in 
  1059.  *    the sequence KeyRecRepContent.caCerts within the CMMFKeyRecRepContent
  1060.  *    structure.  The function will return PR_FALSE if there are 0 certificate
  1061.  *    in the above mentioned sequence.
  1062.  */
  1063. extern PRBool 
  1064.        CMMF_KeyRecRepContentHasCACerts(CMMFKeyRecRepContent *inKeyRecRep);
  1065.  
  1066. /*
  1067.  * FUNCTION: CMMF_POPODecKeyChallContDecryptChallenge
  1068.  * INPUTS:
  1069.  *    inChalCont
  1070.  *        The CMMFPOPODecKeyChallContent to operate on.
  1071.  *    inIndex
  1072.  *        The index of the Challenge to operate on.  The 1st Challenge is
  1073.  *        at index 0, the second at index 1 and so forth.
  1074.  *    inPrivKey
  1075.  *        The private key to use to decrypt the witness field.
  1076.  * NOTES:
  1077.  *    This function uses the private key to decrypt the challenge field
  1078.  *    contained in the appropriate challenge.  Make sure the private key matches 
  1079.  *    the public key that was used to encrypt the witness.  Use 
  1080.  *    CMMF_POPODecKeyChallContentGetPublicValue to get the public value of
  1081.  *    the key used to encrypt the witness and then use that to determine the
  1082.  *    appropriate private key.  This can be done by calling PK11_MakeIDFromPubKey
  1083.  *    and then passing that return value to PK11_FindKeyByKeyID.  The creator of 
  1084.  *    the challenge will most likely be an RA that has the public key
  1085.  *    from a Cert request.  So the private key should be the private key
  1086.  *    associated with public key in that request.  This function will also
  1087.  *    verify the witness field of the challenge.  This function also verifies
  1088.  *    that the sender and witness hashes match within the challenge.
  1089.  *
  1090.  * RETURN:
  1091.  *    SECSuccess if decrypting the witness field was successful.  This does
  1092.  *    not indicate that the decrypted data is valid, since the private key 
  1093.  *    passed in may not be the actual key needed to properly decrypt the 
  1094.  *    witness field.  Meaning that there is a decrypted structure now, but
  1095.  *    may be garbage because the private key was incorrect.
  1096.  *    Any other return value indicates the function could not complete the
  1097.  *    decryption process.
  1098.  */
  1099. extern SECStatus 
  1100.   CMMF_POPODecKeyChallContDecryptChallenge(CMMFPOPODecKeyChallContent *inChalCont,
  1101.                        int                         inIndex,
  1102.                        SECKEYPrivateKey           *inPrivKey);
  1103.  
  1104. /*
  1105.  * FUNCTION: CMMF_DestroyPOPODecKeyChallContent
  1106.  * INPUTS:
  1107.  *    inDecKeyCont
  1108.  *        The CMMFPOPODecKeyChallContent to free
  1109.  * NOTES:
  1110.  *    This function frees up all the memory associated with the 
  1111.  *    CMMFPOPODecKeyChallContent 
  1112.  * RETURN:
  1113.  *    SECSuccess if freeing up all the memory associatd with the 
  1114.  *    CMMFPOPODecKeyChallContent is successful.  Any other return value
  1115.  *    indicates an error while freeing the memory.
  1116.  *
  1117.  */
  1118. extern SECStatus 
  1119.  CMMF_DestroyPOPODecKeyChallContent (CMMFPOPODecKeyChallContent *inDecKeyCont);
  1120.  
  1121. SEC_END_PROTOS
  1122. #endif /* _CMMF_H_ */
  1123.